<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>Sifteo SDK: Execution Environment</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-style-overrides.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<center>
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Sifteo SDK" src="sdk_logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">
   &#160;<span id="projectnumber">v1.0.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
</center>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Home</span></a></li>
      <li class="current"><a href="pages.html"><span>Guides</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Reference</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Execution Environment </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Details on the Sifteo app runtime</p>
<h1>Overview</h1>
<p>Sifteo applications are deployed as ELF binaries, a <a href="http://en.wikipedia.org/wiki/Executable_and_Linkable_Format">standard file format</a>, and run in a specialized sandbox called <b>SVM</b>. Your C++ source is compiled by <a href="http://clang.llvm.org/">Clang</a>, the same top-notch C/C++ compiler used by Apple's iOS. Our <b>slinky</b> optimizing linker and code-generator performs very aggressive whole-program optimizations, so you can continue to use very high-level and modern C++ while keeping your binaries small and fast.</p>
<h1>Memory</h1>
<p>Sifteo applications run on the Sifteo Base, a (very) small mobile device with limited resources. The available memory is divided into read-only and writable address spaces:</p>
<div class="image">
<img src="svm-memory-map.png" alt="svm-memory-map.png"/>
</div>
<h2>Read-Write Data (RAM)</h2>
<p>Applications have a total of <b>32K</b> RAM available, including static allocations and the stack. The system does not provide any built-in dynamic memory allocation facility.</p>
<h3>Stack</h3>
<p>The size of the stack is equal to the total RAM available (32K) minus the total size of your application's static allocations.</p>
<p>In the event that you overflow the stack, the SVM runtime faults and execution of your application is stopped. Overflows are detected in the emulator, making it easy to detect these errors during development.</p>
<dl class="section note"><dt>Note</dt><dd>To get a sense of your stack usage, pass the <code>--svm-stack</code> option to <code>siftulator</code>. During execution it will log a message to the console each time it observes a new low water mark for the stack, indicating its total size.</dd></dl>
<h2>Read-Only Data (ROM)</h2>
<p>The maximum size of a binary on the Sifteo platform is <b>16MB</b>. Currently, this is also the maximum amount of external storage available on the Sifteo Base, so it's not practical to assume that a shipping application can consume all 16MB.</p>
<p>The .elf binary for your application contains all of the code, data, and assets required to run your game, so the total size of the .elf binary is the effective size of your application.</p>
<p>This ROM is relatively slow, but it may be accessed via normal pointers. This memory is demand-paged into a small (16K) cache in system RAM. In some cases this cache may be a bottleneck for application performance. You can examine cache hits and misses by passing the <code>--svm-flash-stats</code> option to <code>siftulator</code>.</p>
<dl class="section note"><dt>Note</dt><dd>If your application is linked for Debug (the default), the .elf binary will also include debug information which does not get installed to hardware. To see the final size of your application, make sure you are linking a release build with <code>make clean &amp;&amp; make RELEASE=1</code>.</dd></dl>
<h1>Concurrency Model</h1>
<h2>Thread of execution</h2>
<p>Your application has only a single thread of execution available to it. Typical applications implement their own main loop, and are driven either by polling for events or by registering callbacks with <a class="el" href="namespace_sifteo_1_1_events.html" title="Namespace of all available event vectors.">Sifteo::Events</a>.</p>
<p>Applications may not create additional threads. Multithreading would require multiple separate stacks, which would use the limited available RAM much less efficiently than a single-threaded application could.</p>
<h2>Events</h2>
<p>It isn't necessary for applications to write their own event dispatch code. Any handlers registered with <a class="el" href="namespace_sifteo_1_1_events.html" title="Namespace of all available event vectors.">Sifteo::Events</a> will be invoked by the system at designated <b>yield points</b>. The <a class="el" href="class_sifteo_1_1_system.html#a3676c1bc1e5891a686d2646d0ec516c6" title="Draw the next frame.">Sifteo::System::paint()</a> function includes an <em>implicit</em> yield point, whereas <a class="el" href="class_sifteo_1_1_system.html#ab3c6ac3aa37edcec5196035c3832f420" title="Temporarily give up control of the CPU.">Sifteo::System::yield()</a> is an <em>explicit</em> yield point.</p>
<p>At a yield point, any number of <a class="el" href="namespace_sifteo_1_1_events.html" title="Namespace of all available event vectors.">Sifteo::Events</a> handlers may be called. From your application's point of view, these invocations look equivalent to a series of function calls placed directly after the yielding API function.</p>
<p>Most events are idempotent operations without any built-in side-effects. For example, if a cube registers several touches between two successive yield points, the touch event callback will only be invoked once.</p>
<p>The big exception to this rule is neighbor events. The system internally updates its matrix of neighbor states, if necessary, during a yield point. Neighbor states as seen by <a class="el" href="struct_sifteo_1_1_neighborhood.html" title="A Neighborhood is a description of all neighbors for a single cube, packed into a small value...">Sifteo::Neighborhood</a> will not change between two yield points. Typical games only yield during <a class="el" href="class_sifteo_1_1_system.html#a3676c1bc1e5891a686d2646d0ec516c6" title="Draw the next frame.">Sifteo::System::paint()</a>, so this means that neighbor states are only updated between frames.</p>
<h2>Multitasking</h2>
<p>The system runs using a combination of cooperative and preemptive multitasking. Many high-priority tasks, such as radio communication and audio output, can preempt the application at any time. These tasks are typically invisible to the application except in places where memory is specifically shared with these tasks, i.e. a <a class="el" href="struct_sifteo_1_1_video_buffer.html" title="A memory buffer which holds graphics data.">Sifteo::VideoBuffer</a>.</p>
<p>Other low-priority system tasks exist which expect to run via a form of cooperative multitasking, similar to how Event dispatch works. These low-priority tasks may be starved if your application spends too much time in very tight loops, without making any system calls. </p>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.3.1-->
<!-- start footer part -->
    <hr class="footer"/>
    <address class="footer">
        <p><a href="http://sifteo.com">Sifteo</a> SDK v1.0.0 <small>(see <a href="https://developers.sifteo.com/sifteosdk">all versions</a>)</small></p>
        <p>Last updated Wed Mar 27 2013, by <a href="http://www.stack.nl/~dimitri/doxygen">Doxygen</a></p>
    </address>
</body>
</html>
